Top | ![]() |
![]() |
![]() |
![]() |
GInputStream * | gdata_download_stream_new () |
GDataService * | gdata_download_stream_get_service () |
GDataAuthorizationDomain * | gdata_download_stream_get_authorization_domain () |
GCancellable * | gdata_download_stream_get_cancellable () |
const gchar * | gdata_download_stream_get_download_uri () |
const gchar * | gdata_download_stream_get_content_type () |
gssize | gdata_download_stream_get_content_length () |
GDataAuthorizationDomain * | authorization-domain | Read / Write / Construct Only |
GCancellable * | cancellable | Read / Write / Construct Only |
glong | content-length | Read |
char * | content-type | Read |
char * | download-uri | Read / Write / Construct Only |
GDataService * | service | Read / Write / Construct Only |
GDataDownloadStream is a GInputStream subclass to allow downloading of files from GData services with authorization from a GDataService under the given GDataAuthorizationDomain. If authorization is not required to perform the download, a GDataAuthorizationDomain doesn't have to be specified.
Once a GDataDownloadStream is instantiated with gdata_download_stream_new()
, the standard GInputStream API can be used on the stream to download
the file. Network communication may not actually begin until the first call to g_input_stream_read()
, so having a GDataDownloadStream around is no
guarantee that the file is being downloaded.
The content type and length of the file being downloaded are made available through “content-type” and
“content-length” as soon as the appropriate data is received from the server. Connect to the
“notify” content-type
and content-length
details to be notified as
soon as the data is available.
The entire download operation can be cancelled using the GCancellable instance provided to gdata_download_stream_new()
, or returned by
gdata_download_stream_get_cancellable()
. Cancelling this at any time will cause all future GInputStream method calls to return
G_IO_ERROR_CANCELLED
. If any GInputStream methods are in the process of being called, they will be cancelled and return G_IO_ERROR_CANCELLED
as
soon as possible.
Note that cancelling an individual method call (such as a call to g_input_stream_read()
) using the GCancellable parameter of the method will not
cancel the download as a whole — just that particular method call. In the case of g_input_stream_read()
, this will cause it to successfully return
any data that it has in memory at the moment (up to the requested number of bytes), or return a G_IO_ERROR_CANCELLED
if it was blocking on receiving
data from the network. This is also the behaviour of g_input_stream_read()
when the download operation as a whole is cancelled.
In the case of g_input_stream_close()
, the call will return immediately if network activity hasn't yet started. If it has, the network activity will
be cancelled, regardless of whether the call to g_input_stream_close()
is cancelled. Cancelling a pending call to g_input_stream_close()
(either
using the method's GCancellable, or by cancelling the download stream as a whole) will cause it to stop waiting for the network activity to finish,
and return G_IO_ERROR_CANCELLED
immediately. Network activity will continue to be shut down in the background.
If the server returns an error message (for example, if the user is not correctly authenticated/authorized or doesn't have suitable permissions to
download from the given URI), it will be returned as a GDataServiceError by the first call to g_input_stream_read()
.
Example 2. Downloading to a File
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
GDataService *service; GDataAuthorizationDomain *domain; GCancellable *cancellable; GInputStream *download_stream; GOutputStream *output_stream; /* Create the download stream */ service = create_my_service (); domain = get_my_authorization_domain_from_service (service); cancellable = g_cancellable_new (); /* cancel this to cancel the entire download operation */ download_stream = gdata_download_stream_new (service, domain, download_uri, cancellable); output_stream = create_file_and_return_output_stream (); /* Perform the download asynchronously */ g_output_stream_splice_async (output_stream, download_stream, G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE | G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET, G_PRIORITY_DEFAULT, NULL, (GAsyncReadyCallback) download_splice_cb, NULL); g_object_unref (output_stream); g_object_unref (download_stream); g_object_unref (cancellable); g_object_unref (domain); g_object_unref (service); static void download_splice_cb (GOutputStream *output_stream, GAsyncResult *result, gpointer user_data) { GError *error = NULL; g_output_stream_splice_finish (output_stream, result, &error); if (error != NULL && g_error_matches (error, G_IO_ERROR, G_IO_ERROR_CANCELLED) == FALSE)) { /* Error downloading the file; potentially an I/O error (GIOError), or an error response from the server * (GDataServiceError). You might want to delete the newly created file because of the error. */ g_error ("Error downloading file: %s", error->message); g_error_free (error); } } |
GInputStream * gdata_download_stream_new (GDataService *service
,GDataAuthorizationDomain *domain
,const gchar *download_uri
,GCancellable *cancellable
);
Creates a new GDataDownloadStream, allowing a file to be downloaded from a GData service using standard GInputStream API.
As well as the standard GIO errors, calls to the GInputStream API on a GDataDownloadStream can also return any relevant specific error from
GDataServiceError, or GDATA_SERVICE_ERROR_PROTOCOL_ERROR
in the general case.
If a GCancellable is provided in cancellable
, the download operation may be cancelled at any time from another thread using g_cancellable_cancel()
.
In this case, any ongoing network activity will be stopped, and any pending or future calls to GInputStream API on the GDataDownloadStream will
return G_IO_ERROR_CANCELLED
. Note that the GCancellable objects which can be passed to individual GInputStream operations will not cancel the
download operation proper if cancelled — they will merely cancel that API call. The only way to cancel the download operation completely is using
this cancellable
.
service |
||
domain |
the GDataAuthorizationDomain to authorize the download, or |
[allow-none] |
download_uri |
the URI to download; this must be HTTPS |
|
cancellable |
a GCancellable for the entire download stream, or |
[allow-none] |
Since: 0.9.0
GDataService *
gdata_download_stream_get_service (GDataDownloadStream *self
);
Gets the service used to authorize the download, as passed to gdata_download_stream_new()
.
Since: 0.5.0
GDataAuthorizationDomain *
gdata_download_stream_get_authorization_domain
(GDataDownloadStream *self
);
Gets the authorization domain used to authorize the download, as passed to gdata_download_stream_new()
. It may be NULL
if authorization is not
needed for the download.
the GDataAuthorizationDomain used to authorize the download, or NULL
.
[transfer none][allow-none]
Since: 0.9.0
GCancellable *
gdata_download_stream_get_cancellable (GDataDownloadStream *self
);
Gets the GCancellable for the entire download operation, “cancellable”.
Since: 0.8.0
const gchar *
gdata_download_stream_get_download_uri
(GDataDownloadStream *self
);
Gets the URI of the file being downloaded, as passed to gdata_download_stream_new()
.
Since: 0.5.0
const gchar *
gdata_download_stream_get_content_type
(GDataDownloadStream *self
);
Gets the content type of the file being downloaded. If the Content-Type
header has not yet
been received, NULL
will be returned.
Since: 0.5.0
gssize
gdata_download_stream_get_content_length
(GDataDownloadStream *self
);
Gets the length (in bytes) of the file being downloaded. If the Content-Length
header has not yet
been received from the server, -1
will be returned.
Since: 0.5.0
typedef struct _GDataDownloadStream GDataDownloadStream;
All the fields in the GDataDownloadStream structure are private and should never be accessed directly.
Since: 0.5.0
typedef struct { } GDataDownloadStreamClass;
All the fields in the GDataDownloadStreamClass structure are private and should never be accessed directly.
Since: 0.5.0
“authorization-domain”
property“authorization-domain” GDataAuthorizationDomain *
The authorization domain for the download, against which the “authorizer” for the “service” should be
authorized. This may be NULL
if authorization is not needed for the download.
Owner: GDataDownloadStream
Flags: Read / Write / Construct Only
Since: 0.9.0
“cancellable”
property “cancellable” GCancellable *
An optional cancellable used to cancel the entire download operation. If a GCancellable instance isn't provided for this property at
construction time (i.e. to gdata_download_stream_new()
), one will be created internally and can be retrieved using
gdata_download_stream_get_cancellable()
and used to cancel the download operation with g_cancellable_cancel()
just as if it was passed to
gdata_download_stream_new()
.
If the download operation is cancelled using this GCancellable, any ongoing network activity will be stopped, and any pending or future
calls to GInputStream API on the GDataDownloadStream will return G_IO_ERROR_CANCELLED
. Note that the GCancellable objects which can be
passed to individual GInputStream operations will not cancel the download operation proper if cancelled — they will merely cancel that API
call. The only way to cancel the download operation completely is using “cancellable”.
Owner: GDataDownloadStream
Flags: Read / Write / Construct Only
Since: 0.8.0
“content-length”
property “content-length” glong
The length (in bytes) of the file being downloaded. This will initially be -1
, and will be populated as soon as
the appropriate header is received from the server. Its value will never change after this.
Owner: GDataDownloadStream
Flags: Read
Allowed values: >= -1
Default value: -1
Since: 0.5.0
“content-type”
property “content-type” char *
The content type of the file being downloaded. This will initially be NULL
, and will be populated as soon as the appropriate header is
received from the server. Its value will never change after this.
Owner: GDataDownloadStream
Flags: Read
Default value: NULL
Since: 0.5.0
“download-uri”
property “download-uri” char *
The URI of the file to download. This must be HTTPS.
Owner: GDataDownloadStream
Flags: Read / Write / Construct Only
Default value: NULL
Since: 0.5.0
“service”
property“service” GDataService *
The service which is used to authorize the download, and to which the download relates.
Owner: GDataDownloadStream
Flags: Read / Write / Construct Only
Since: 0.5.0